// IFreeZzaphContentProviderPlugin.cs
// 
// Copyright © 2009 FreeZzaph
//
// This program is free software: you can redistribute it and/or modify
// it under the terms of the GNU General Public License as published by
// the Free Software Foundation, either version 3 of the License, or
// (at your option) any later version.
//
// This program is distributed in the hope that it will be useful,
// but WITHOUT ANY WARRANTY; without even the implied warranty of
// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
// GNU General Public License for more details.
//
// You should have received a copy of the GNU General Public License
// along with this program.  If not, see <http://www.gnu.org/licenses/>.
//

using System;
using System.Collections.Generic;

namespace LibFreeZzaph
{
	
	/// <summary>
	/// <para>
	/// The FreeZzaph content provider plug-in interface. Any plug-in that is to
	/// be used for downloading with LibFreeZzaph needs to adhere to this
	/// interface.
	/// </para>
	/// <para>
	/// FreeZzaph content provider plug-ins will be provided in a dll file, conventionally
	/// named after the site the plug-in downloads from, such as "SexSite.dll".
	/// </para>
	/// <para>
	/// Each plug-in file should only contain a single plug-in, so if you
	/// want to create several plug-ins, you should create separate dlls.
	/// We've chosen this policy because we believe that each plug-in should
	/// only represent one website.
	/// </para>
	/// <para>
	/// There are no restrictions or rules regarding namespaces or class
	/// names, although it is asked that only official FreeZzaph plug-ins use
	/// the LibFreeZzaph namespace, even though it would be possible for others to use
	/// the same namespace. Although we impose no restrictions on naming,
	/// following a naming scheme probably won't hurt. The official FreeZzaph
	/// naming scheme for plug-ins is [the name of the site] + "Plugin", such
	/// as "SexSitePlugin". Feel free to adopt this naming scheme for your plug-ins.
	/// </para>
	/// <para>
	/// The plug-in class and any and all related classes should under no
	/// ordinary circumstances throw any exceptions except the PluginException.
	/// Applications that use LibFreeZzaph are only required to handle that exception
	/// when calling LibFreeZzaph's methods, and LibFreeZzaph plug-ins,
	/// so throwing any other exceptions may cause applications to terminate,
	/// which will be inconvenient for the user. Official FreeZzaph applications
	/// will handle all exceptions, although we reserve the right to blacklist
	/// or disable plug-ins that throw other exceptions than the PluginException.
	/// </para>
	/// </summary>
	public interface IFreeZzaphContentProviderPlugin : IFreeZzaphPlugin
	{	
		/// <value>
		/// The title of the plug-in. This can be longer, and more thorough than
		/// the name, such as "Sex Site.com — The best porn on the Internet!".
		/// </value>
		string Title { get; }
		
		/// <value>
		/// A dictionary over category groups. The key for each group should
		/// be a simple identifier, such as "pictures" and "movies".
		/// </value>
		IDictionary<string, CategoryGroup> CategoryGroups { get; }
		
		/// <summary>
		/// Plug-in initialization routine. Any required initialization
		/// can be done here. The provided plug-in manager may be used by
		/// plug-ins that provide more advanced features.
		/// </summary>
		/// <param name="pm">
		/// See <see cref="IPluginManager"/> for details on how you can use the
		/// plug-in manager to extend your plug-in.
		/// </param>
		void Initialize(IPluginManager pm);
	}
}
